<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>All for Good API Reference Guide</title>
</head>

<body>
<h1>All for Good  API Reference Guide</h1>
<h2>Introduction</h2>
<p>The All for Good  application programming interface (API) allows client applications to retrieve and view the content of <a href="http://www.allforgood.org/">http://www.allforgood.org/</a>, which collects and presents volunteer opportunities posted to numerous, disparate sites. Your client application can use the All for Good API to request a list of volunteer opportunities using a number of parameters documented here.</p>
<p>Please note that your use of the API is subject to the <a href="/api_tos">API Terms of Service</a>.</p>
<h2>Contents</h2>
<p><a href="#Audience">Audience</a></p>
<p><a href="#Licenses">Licenses</a></p>
<p><a href="#Access">Access</a></p>
<p><a href="#Parameters">Query parameters</a></p>
<p><a href="#Formats">Output formats</a></p>
<p><a href="#Fields">Output fields</a></p>
<p><a href="#Examples">Examples</a></p>
<p><a href="#Elements">Elements</a></p>
<p><a href="#Notes">Developer notes and requests</a></p>
<h2 id="Audience">Audience</h2>
<p>This document is intended for programmers who want to write client applications that can interact with All for Good, an open source aggregator of volunteer opportunities. It provides reference documentation for using the All for Good  API.</p>
<p>This document doesn't contain information about the programming-language client libraries. For client-library reference information, see related programming-language-specific guides.</p>
<h2 id="Licenses">Licenses</h2>
<p>It should be noted that the use of particular subsets of All for Good data may be subject to restrictions and third party licenses.  For example, VolunteerMatch supplies listings data under a Creative Commons license, specifically <a href="http://creativecommons.org/licenses/by-nc-sa/3.0/">Attribution-Noncommercial-Share Alike 3.0</a>. Partners are expected to observe such compliance requirements.     
</p>
<h2 id="Access">Access</h2>
<p>First, request a key to use the All for Good API by completing the <a href="http://spreadsheets.google.com/viewform?hl=en&formkey=cmV2MWhwSmpBMUdZV3dtRG5UWFljdlE6MA..">API Key form</a>. Once that request has been fulfilled, you may then use the API  available at:<br />
<a href="http://www.allforgood.org/api/volopps">http://www.allforgood.org/api/volopps</a></p>
<p>As a <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a>-based API, All for Good provides all output over HTTP at distinct <a href="http://en.wikipedia.org/wiki/Uniform_Resource_Identifier">URIs</a>, which makes it easy to test applications with browsers and command-line web clients. All for Good contains listings of volunteer opportunities, which today are defined as events (offline or online), optionally containing locations and start-end times.</p>
<p>In their simplest form, listings have just a title, description and basic contact, time and location information.  In their fullest form, listings can contain dozens of detailed fields, as described in the <a href="#Elements">Elements</a> section and associated <a href="http://code.google.com/p/allforgood/source/browse/trunk/spec/spec0.1.html">specification</a>. Because of the short lifespan of these posts, there is little point in storing results.</p>
<h2 id="Parameters">Query parameters</h2>
<p>All for Good uses <a href="http://code.google.com/apis/gdata/docs/2.0/reference.html#Queries">Google conventions on query parameters</a>, , e.g. q=... is used for keyword search, num= specifies the number of results and start= sets offset for pagination.</p>
<p>The syntax for API calls requires following the aforementioned All for Good  API URL (<a href="http://www.allforgood.org/api/volopps">http://www.allforgood.org/api/volopps</a>) with a question mark (?) and then a parameter name, equal sign (=), and value. Here's the syntax for constructing API calls:<br />
  <code>http://www.allforgood.org/api/volopps?<em>parameter_name</em>=<em>value</em></code></p>
<p>For instance, a query for location would use the vol_loc parameter and resemble:<br />
<code>http://www.allforgood.org/api/volopps?vol_loc=<em>City</em>+<em>Name</em>,<em>STATEABBREV</em></code></p>
<p>Multiple parameter and value combinations may be included in a single call by joining them with an ampersand(&amp;), like so:<br />
<code>http://www.allforgood.org/api/volopps?<em>parameter_name1</em>=<em>value</em>&amp;<em>parameter_name2</em>=<em>value</em></code></p>
<p>The All for Good Data API supports the following query parameters:<br />
</p>
<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Meaning</th>
      <th>Values</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>num</code></td>
      <td>The number of results to return.</td>
      <td><p>Default value: 10</p>
      <p>Expected values: any integer</p></td>
    </tr>
    <tr>
      <td><code>output</code></td>
      <td><p>The output format for presenting the results.</p>
      <p><strong>Important</strong>: This parameter is required for all uses other than debugging. Append the All for Good  API URI with <code>&amp;output=rss</code> to receive the output in a machine-readable format. See the<em> <a href="#Formats">Output formats</a></em> section for additional details.</p></td>
      <td><p>Default value: html (This should be used only for debugging and otherwise overridden with another format, such as RSS, for production use.)</p>
      <p>Expected values: rss, json</p></td>
    </tr>
    <tr>
      <td><code>provider</code></td>
      <td>The provider of the volunteer opportunity, meaning the site or organization posting the event description. </td>
      <td><p>Default value: all providers</p>
      <p>Expected values: the codename for any of the current providers, such as usaservice.org, craigslist.org, networkforgood, idealist.org, HandsOn Network, and volunteermatch.org</p></td>
    </tr>
    <tr>
      <td><code>q</code></td>
      <td>The keyword search string, which offers support for most Google features.</td>
      <td><p>Default value: none</p>
      <p>Expected values: any string,  including quoted phrases (&quot;some terms&quot;) , and exclusions (-excluded_term)</p></td>
    </tr>
    <tr>
      <td><code>start</code></td>
      <td>The starting page offset for search results.</td>
      <td><p>Default value: 1</p>
      <p>Expected value: any integer between 1 and 999</p></td>
    </tr>
    <tr>
      <td><code>timeperiod</code></td>
      <td>Provides period-based date filtering and populates vol_startdate and  vol_enddate. <strong>Important</strong>: This overwrites values  already set in vol_startdate and  vol_enddate.</td>
      <td>Expected values: today, this_month, this_weekend, or this_week</td>
    </tr>
    <tr>
      <td><code>vol_dist</code></td>
      <td>Maximum distance from center point, in miles. <strong>Important</strong>: Requires vol_loc to be set.</td>
      <td><p>Default value: null</p>
      <p>Expected value: any integer between 1 and 99</p></td>
    </tr>
    <tr>
      <td><code>vol_loc</code></td>
      <td>The center point for geographic-based searches.</td>
      <td><p>Default value: null</p>
      <p>Expected values: comma-separated string of the location consisting of address (or intersection), city and state, just city and state, a landmark, or numeric coordinates, expressed as either <code><em>City</em>+<em>Name</em>,<em>STATEABBREV</em></code> or<code><em> latitude</em>,<em>longitude</em></code>.</p></td>
    </tr>
    <tr>
      <td><code>vol_enddate</code></td>
      <td>The last or final date of volunteer opportunities returned.</td>
      <td><p>Default value: the numeric equivalent of 1000 days from today</p>
      <p>Expected values: Any (future) date in the form: YYYY-MM-DD</p></td>
    </tr>
    <tr>
      <td><code>vol_startdate</code></td>
      <td>The first or earliest date of volunteer opportunities returned.</td>
      <td><p>Default value: the numeric equivalent of tomorrow</p>
      <p>Expected values: Any (future) date in the form: YYYY-MM-DD</p></td>
    </tr>
  </tbody>
</table>
<h2 id="Formats">Output formats</h2>
<p>The All for Good  API provides its output in the following formats:</p>
<ul>
  <li><em>JSON</em> - A machine-readable format that is currently recommended for all uses other than debugging. You can specify this setting by appending the API call with: <code>&amp;output=json</code></li>
  <li><em>RSS</em> - A machine-readable format that is currently recommended for all uses other than debugging. You can specify this setting by appending the API call with: <code>&amp;output=rss</code></li>
  <li><em>HTML</em> - A  human-readable format that's currently dedicated to debugging. This is the default and will appear whenever you load the API without the output parameter and can be manually set with: <code>&amp;output=html</code></li>
</ul>
<p>In addition, many more output formats are planned, including XML (FPXML), xSV (comma, tab, etc. separated values) and more. Ask <a href="mailto:footprint-eng@googlegroups.com">us</a> and we'll quickly provide them. Return to this page or visit the <a href="http://code.google.com/p/allforgood/">All for Good project site</a> for <a href="http://code.google.com/p/allforgood/updates/list">updates</a>.</p>
<h2 id="Fields">Output fields</h2>
<p>Generally, the output fields correspond to the input fields found in FPXML (see the <a href="#Elements">Elements</a> section), with a few extra fields:</p>
<ul>
  <li><em>categories</em> - We run a system of classifiers against each listing to sort it into relevant categories.  They appear in this field as a comma-separated last.</li>
  <li><em>quality_score</em> - Internally, we score each record using heuristics to predict what will be popular with users, then use this for ranking.  This field contains that value, between 0.0 and 1.0</li>
  <li><em>pageviews</em> - Whenever possible, trusted clients report to All for Good the number of pageviews from each listing.  This value is the total lifetime pageviews for this listing.</li>
</ul>
<h2 id="Examples">Examples</h2>
<p>Here are some example queries made against the All for Good  API to help you see how the API works. We've appended <code>&amp;output=rss</code> to each query to get machine-readable output.</p>
<p>Listings near San Francisco:<br />
  <a href="http://www.allforgood.org/api/volopps?vol_loc=San+Francisco,CA&amp;output=rss">http://www.allforgood.org/api/volopps?vol_loc=San+Francisco,CA&amp;output=rss</a><br />
  </p>
<p>Listings within 10 miles of 94703:<br />
<a href="http://www.allforgood.org/api/volopps?q=park&amp;vol_loc=94703&amp;vol_dist=10&amp;output=rss">http://www.allforgood.org/api/volopps?q=park&amp;vol_loc=94703&amp;vol_dist=10&amp;output=rss</a></p>
<p>Listings near a particular latitude and longitude:<br />
  <a href="http://www.allforgood.org/api/volopps?q=park&amp;vol_loc=37.8524741,-122.2738958&amp;output=rss">http://www.allforgood.org/api/volopps?q=park&amp;vol_loc=37.8524741,-122.2738958&amp;output=rss</a></p>
<p>Up to 50 listings containing the term &quot;park&quot;:<br />
  <a href="http://www.allforgood.org/api/volopps?q=park&amp;num=50&amp;output=rss">http://www.allforgood.org/api/volopps?q=park&amp;num=50&amp;output=rss</a></p>
<p>Park listings starting May 10th or later:<br />
<a href="http://www.allforgood.org/api/volopps?q=park&amp;vol_startdate=2009-05-10&amp;output=rss">http://www.allforgood.org/api/volopps?q=park&amp;vol_startdate=2009-05-10&amp;output=rss</a></p>
<p>And here is an example of an All for Good query called from a program, this one written in Java:</p>
<pre>
URLConnection connection;
URL url = new URL
     &quot;http://www.allforgood.org/api/volopps?output=rss&amp;vol_loc=&quot; +
     location);
connection = url.openConnection();
connection.connect();
InputStream stream = connection.getInputStream();</pre>
<h2 id="Elements">Elements</h2>
<p>All for Good stores one record per location, i.e. if an event has multiple locations, there's one record per location.  Likewise, for repeated events, we store one record per time range. These elements are described in the <a href="/spec">All for Good XML specification for data received from providers.</a></p>
<h2 id="Notes">Developer notes and requests</h2>
<ul>
  <li><em>maximum results</em> - As with most search engines, we have limits on the number of result records, both per query (999) and total (TBD). Please ask us if you need to download all results, and explain why.</li>
  <li><em>ranking / sorting</em> -  Record sorting ('ranking') is hardcoded right now, but it's pretty easy to add new sorting functions-- please ask us.</li>
  <li><em>keyword stemming/plurals/etc</em>.  - We use Google's search engine as the underlying provider for keyword queries, so it should match alternate word forms.  As with all search engines, please don't rely on this-- and don't hesitate to file bugs with us if you don't get expected behavior.</li>
  <li><em>keyword queries on various fields</em> - q= queries all fields.  There's no way to restrict to fewer fields.</li>
  <li><em>skills field</em> - Due to the data from providers, the skills field is unstructured, i.e. can't run restriction-searches on it.  Sorry!</li>
  <li><em>repeated URL parameters</em> - If multiple URL parameters are provided, we take the last of them, e.g. &amp;cats=foo&amp;cats=bar is the same as &amp;cats=bar.</li>
  <li><em>querying on the skills field </em>- Not supported beyond : keyword search only (providers  have only longhand descriptions).</li>
  <li><em>unknown URL parameters</em> - Unknown args result in an error-- HTTP 404 with custom error msg.</li>
  <li><em>bookmarking query URLs</em> - Yes, you may bookmark query URLs including emailing them, linking to them, etc. </li>
  <li><em>caching results</em> - Yes, you may cache results for at least 1 hour.  Please contact us if you want to cache for longer.</li>
  <li><em>HTTP compressed output</em> - We can probably add this if you need-- please ask and explain why.</li>
</ul>
</body>
</html>
